'''
Created on Jul 26, 2010

@author: adolfo

Module that defines interfaces with methods that SMSGateways should follow.
'''
class SMSGateway :
    """Interface that defines the methods an SMSGateway should provide and
    the conventions it should follow.
    """
    #Pylint reports some warnings in this class by mistake    
    #pylint: disable=W0232
    
    def start_service(self):
        """Do any initialization required to start sending and receiving SMS
        messages. For example start listening at some port for notifications.
        """
        raise NotImplementedError( "The class does not implement this method." )

    def stop_service(self):
        """Release any system resources acquired (sockets, files, etc.) and
        stop the threads or processes that were started.
        """
        raise NotImplementedError( "The class does not implement this method." )

    def get_phone_number(self):
        """Returns the phone number of the GSM modem the gateway is using to
        send and receive SMS messages.
        """
        raise NotImplementedError( "The class does not implement this method." )

    def send_message(self, message):
        """Send a message via SMS to the specified telephone number.
        ``message`` should be an instance of ``Message``."""
        raise NotImplementedError( "The class does not implement this method." )
    
    def add_sms_listener(self, sms_listener):
        """Registers an SMSListener to be notified about SMS message events."""
        raise NotImplementedError( "The class does not implement this method." )
    
    def remove_sms_listener(self, sms_listener):
        """Removes an SMSListener from the list of registered listeners that
        are notified about SMS message events. Only the first appearance of the
        instance is removed.
        """
        raise NotImplementedError( "The class does not implement this method." )

class SMSListener :
    """Interface that defines the methods an object interested in being notified
    about SMS events should implement.
    """
    #Pylint reports some warnings in this class by mistake    
    #pylint: disable=W0232,R0903

    
    def message_received(self, message, notifier):
        """Method invoked by instances of SMSGateway to notify listeners about
        the arrival of an SMS message.
        
        message -- An instance of ``Message``
        
        notifier -- The instance of ``SMSGateway`` that received the message.
        """
        raise NotImplementedError( "The class does not implement this method." )

class Message :
    """Class that models an SMS message and its related data (sender, receiver,
    UDH, original binary message, etc.). Not every message contains all of the
    data fields. Instances of ``Message`` contain a dictionary named
    ``data`` that uses the constants defined in the class as keys.
    """
    #Pylint reports some warnings in the following class by mistake    
    #pylint: disable=R0903

    
    def __init__(self):
        """Initializes the dictionary ``data`` to a dictionary that only
        contains empty data for each key.  The ``Message.UDH`` key is 
        associated to the empty string (value used for text SMS messages),
        and the rest of the keys are associated to ``None``
        """
        self.data = {Message.UDH : ""
                     , Message.SENDER_PHONE_NUMBER : None
                     , Message.RECEIVER_PHONE_NUMBER : None
                     , Message.ORIGINAL_BINARY_MESSAGE : None}
    
    # Key for the phone number of the sender of the SMS message, in the
    # dictionary `data`
    SENDER_PHONE_NUMBER = "Sender phone number"
    
    # Key for the phone number of the receiver of the SMS message, in the
    # dictionary `data`.
    RECEIVER_PHONE_NUMBER = "Receiver phone number"
    
    # Key for the original SMS message in a binary form, in the dictionary
    # `data`.
    ORIGINAL_BINARY_MESSAGE = "Original binary message"
    
    # Key for the message's user data header in the dictionary `data`.
    UDH = "User data header"
